Refresh and Access Tokens

Token Authentication and Management APIs

Public APIs for managing RefreshTokens and APIAccessTokens for the user.

tip

If your Organization is using SSO, like Okta, LDAP, and etc., you need to use the UI to create a RefreshToken by going to base-url/account/auth.

Description

• APIAccessToken: A short-lived access token, which can be passed as the value for the 'TOKEN' header in the requests for other APIs.

• RefreshToken: A long living token the users can use to manage and create API Access Tokens, which can be used to interact with the other APIs.

Remember

The default expiration times for RefreshToken and APIAccessToken are 60 days and 24 hours respectively. They can be configured using the _conf by the Server Admins if you need different expiration times. For example:

Login to the  server, and using \`\_conf\`, update the RefreshToken lifespan (in days),

\_conf .authentication.token.refresh\_token\_lifespan -s 180

\-- sets the expiration time for any new RefreshTokens created after the change to be after 180 days(6 months) from creation.

Login to the  server, and using \`\_conf\`, update the

APIAccessToken lifespan (in hours),

\_conf .authentication.token.access\_token\_lifespan -s 2

\-- sets the expiration time for any new APIAccessTokens created after the change to be after 2 hours from creation.

All these APIs, except Create RefreshToken, are supported in SAML 2.0 Single Sign On environments. If you're using the SAML authentication, you can create the refresh tokens using the GUI by visiting <BASE_URL>/account/auth page.

Open API 3.0 Specification

The above APIs are also described using the Open API 3.0 Specification (OAS). OAS is a broadly adopted industry standard for describing APIs.

To see the specification, replace {InstanceURL} below with your instance's URL and visit the link:

{InstanceURL}/openapi/api\_authentication/

Note: The Swagger UI is not enabled by default on an instance. Please set the flag .feature_flags.enable_swagger to True using _conf.

Create RefreshToken

Creates a new RefreshToken for the user.

URL

POST /integration/v1/createRefreshToken/

Data Parameters

Name	Type	Description	Required
username	string	Username of the user on Alation. Example: "basava@alation.com"	Yes
password	string	Password associated with the user on Alation. Example: "P@s$w0rd!"	Yes
name	string	Create the RefreshToken with this name. Example: "TableauRefreshToken"	Yes

Response Structure

Content-Type: text/json

Status: 201 CREATED

Name	Type	Description
refresh_token	string	RefreshToken generated for the user in Alation. Example: "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
user_id	integer	User ID associated with the refresh token who generated this token on Alation. Example: 102
created_at	dateTime	Timezone aware date-time at which the refresh token is created at.
name	string	Name of the RefreshToken. Example: "TableauRefreshToken"
token_expires_at	dateTime	Timezone aware date-time until which the RefreshToken is valid for.
token_status	string	Current status of the RefreshToken. Enum: "active", "expired", "revoked" Example: "active"

All Responses

Code	Description
201	Created
400	Malformed Request
401	Unauthorized bad/missing token
403	Forbidden User cannot edit this resource
404	The specified resource was not found
500	Internal Server Error

Code Samples

cURL

BASE\_URL="https://yourcompany.com/integration/v1/createRefreshToken/"

USER\_ID="dave@example.com"

PASSWORD="secret"

NAME="My Precious"

\# Create RefreshToken for user dave@example.com

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "${BASE\_URL}"

\--data-urlencode "username=${USER\_ID}" --data-urlencode "password=${PASSWORD}" --data-urlencode "name=${NAME}" -v

Python

\# Replace username, name and password with your login ID, desired token name and password.

data = {'username':'dave@example.com', 'password':'secret', 'name': 'My Precious Token'}

ION\_AT\_YOUR\_COMPANY\_URL="https://yourcompany.com"

\# Create RefreshToken for user: dave@example.com

response = requests.post(

'{base\_url}/integration/v1/createRefreshToken/'.format(base\_url=ION\_AT\_YOUR\_COMPANY\_URL

), data=data)

print(response.text)

\# Sample Response

\# {

\# "user\_id": 1151,

\# "created\_at": "2020-07-15T16:08:09.673391-07:00",

\# "token\_expires\_at": "2020-09-13T16:08:09.672850-07:00",

\# "token\_status": "ACTIVE",

\# "last\_used\_at": null,

\# "name": "My Precious Token",

\# "refresh\_token":

\# "mnuM-jp7uAOLWsG7ojs6rY-wweh2JVfKmNtWyPgVs-RdIysp4QyEHJtdd5Q5fECWEOsGVYxZ0eHy37j\_lqoPcQ"

\# }